home *** CD-ROM | disk | FTP | other *** search
/ NetNews Offline 2 / NetNews Offline Volume 2.iso / news / comp / lang / c++-part2 / 10708 < prev    next >
Encoding:
Text File  |  1996-08-05  |  8.0 KB  |  229 lines
  1. Path: inforamp.net!ts10-07
  2. From: rmorin@inforamp.net (Randy Charles Morin)
  3. Newsgroups: comp.lang.c++
  4. Subject: Re: Coding Standards
  5. Date: Sat, 09 Mar 96 17:40:43 GMT
  6. Organization: MiddleWorld SoftWare
  7. Message-ID: <4hsfrc$pmm@sam.inforamp.net>
  8. References: <4hj8ek$elu@sam.inforamp.net> <4hktar$5o2@galaxy.ucr.edu>
  9. NNTP-Posting-Host: ts10-07.tor.inforamp.net
  10. X-Newsreader: News Xpress Version 1.0 Beta #4
  11.  
  12. In article <4hktar$5o2@galaxy.ucr.edu>, thp@cs.ucr.edu (Tom Payne) wrote:
  13. >By and large these are good guidelines, and I'd appreciate a copy of them.
  14. >Some, however, require some exceptions, e.g.:
  15.  
  16. Ya, common guys.  Source files should end with .cc and headers with .hh?  
  17. That's contrary to any standard in existence.  A set of coding standards 
  18. should be straight forward, easy to follow and should not contradict normal 
  19. programming practices.  The standards I described were exhaustive, 
  20. contradictory to normal programming practices and have already been excused by 
  21. the contractee.  
  22.  
  23. I'll attach a real coding standard, so that you guys who've never seen real 
  24. standards before can be amazed by them.  I can't send you a copy of the 
  25. company's coding standard, since that would be in violation of my contract.  
  26. This reasonable standard was developped at another company that I did work 
  27. for.  I'm under no obligation not to publish it.  Some of the standards apply 
  28. only because of the working environment at the company and shouldn't be taken 
  29. literally in the real world.  That is, if you don't have a development server, 
  30. that's OK, most companies don't.
  31.  
  32. Agrivar 
  33.  
  34. ---------------------------------------------------------------------
  35.  
  36. Coding Standards
  37.  
  38. 1 General
  39.  
  40. 1.    All source code must be located in the development directories on the 
  41. development Server.
  42.  
  43. 2.    All C and C++ header files (include files) must have the ".h" 
  44. extension (all class definitions must have the ".hpp" or ô.hö extension), all 
  45. C source files must have the ".c" extension and all C++ source files must have 
  46. the ".cpp" extension.
  47.  
  48. 3.    We must use object oriented programming where possible.  Where it is 
  49. not possible to use object oriented programming, we must use functional 
  50. programming.  If it is not possible to use object oriented programming or 
  51. functional programming, we will abandon the functionality we are attempting to 
  52. add.
  53.  
  54. 4.    Command line make procedures must be located solely in make files.  
  55. This means no batch file commands that execute the compiler, linker, librarian 
  56. or maker.
  57.  
  58. 5.    Warnings and errors messages must not be suppressed when compiling or 
  59. linking and all warnings and errors must be removed before completion.
  60.  
  61. 6.    We must not use the standard function assert(BOOL) unless it is 
  62. thoroughly documented and the production version is made without any assert 
  63. commands.  The assert function is a debugging tool not a production version 
  64. function.
  65.  
  66. 7.    Do not return pointers to data space that was local to the function 
  67. that is returning the pointer.  If you must return a pointer to data space, 
  68. then pass the data space as a parameter to the function that will be returning 
  69. the pointer.
  70.  
  71. 8.    If you modify a standard header file or rebuild a standard object 
  72. file, put the modified header, source and object files in the same directory 
  73. structure as our header, source and object files.  This way other projects 
  74. will not include this modification and future programmers will know that the 
  75. standard file was modified.
  76.  
  77. 9.    If you receive a pointer as a parameter where the data pointed to by 
  78. the pointer will not be modified, then the parameter declaration should 
  79. include the const modifier.
  80.  
  81. 10.    All header, source, make and resource files should be located in a 
  82. base directory.
  83.  
  84. 11.    C++ inline definitions should be discouraged.  Reason:  A class 
  85. accessor method is used so that if the data member's format is changed the 
  86. accessor method can be changed such that it continues to return the same 
  87. format.  Therefor, if the accessor method is inline and the data member's 
  88. format is changed, then all objects that call the accessor would need 
  89. recompilation rather than only the object that contains the method.
  90.  
  91. 12.    All C++ classes must be checked into the class library.
  92.  
  93. 13.    Data members of classes should be private where possible and accessors 
  94. should be used to give access to users.
  95.  
  96.  
  97.  2 File Formats
  98.  
  99. 2.1 Header Files
  100.  
  101. 1.    All header files should begin with the two lines and end with the one 
  102. line outlined below.  Do not use the define macro.
  103.  
  104.     #ifndef PROJECTCODE_FILENAME_H
  105.     #define PROJECTCODE_FILENAME_H
  106.     .
  107.     .
  108.     .
  109.     #endif
  110.  
  111. 2.    If a header file requires that a second header file be included in the 
  112. source listing that includes the first header file, then the first header file 
  113. must include the second header file.  In other words, you should be able to 
  114. compile your headers.
  115.  
  116. 3.    A header file may include only one object.  The implementation of the 
  117. object may be distributed over several source files, but two objects must not 
  118. be implemented in one source file.
  119.  
  120. 4.    The header file must contain a comment header.  The comment header 
  121. will have the following format.  In the example the header filename is 
  122. "example.h".
  123.  
  124.     /*
  125.         implementation: example.c
  126.     */
  127.  
  128. 5.    A header file should not contain any identifiers, they should contain 
  129. only type definitions.  The only exception is C++ class definitions may 
  130. contain inline functions.
  131.  
  132. 6.    If you one need the class name to compile a header, donÆt include the 
  133. classes header, include only the existence of the class.  The code below on 
  134. the left is correct and the code below on the right is not.
  135.  
  136.  #ifndef HEADEROFRC1_H
  137. class c1;
  138. #endif
  139. class c2
  140. {
  141.     void f(c1 * p);
  142. };
  143.  #include <headerforc1.h>
  144. class c2
  145. {
  146.     void f(c1 * p);
  147. };
  148.  
  149.  
  150. 2.2 Source Files
  151.  
  152. 1.    Every source file must have an associated header file that defines 
  153. every function, type definition, structure and class.  Source files may not 
  154. include any definitions (this includes macro definitions).  The source file 
  155. and header file should have the prefix wherever possible.
  156.  
  157. 2.    The source file must contain a comment header.  The comment header 
  158. will have the following format.  In the example the header filename is 
  159. "example.c".
  160.  
  161.     /*
  162.         definition: example.h
  163.         purpose: To serve as an example
  164.     */
  165.  
  166.     ...During the first modification of a source for version x, the writer 
  167. should delete all modifications for versions previous to x.  The result would 
  168. be that all modifications described in the header are for the version in which 
  169. that source was last modified.
  170.  
  171. 3.    Each function will have a comment header.  The comment header will 
  172. have the following format.  Note the use of the stars to highlight where each 
  173. function begins.
  174.  
  175.     /**********************************
  176.         prototype: example.h (this line is necessary only if it is 
  177. different from the source header, but it does not hurt to include it anyway).
  178.         purpose: To serve as an example
  179.     */
  180.  
  181. 4.    C precompiler macro definitions must be placed in header file when 
  182. possible, although it is understood that this is not always possible.
  183.  
  184.  
  185.  3 Naming Conventions
  186.  
  187. 1.    All class names should begin with the prefix BELL.  Example: 
  188. BELLSuperClass.
  189.  
  190. 2.    Identifiers should contain no underline characters.  The first letter 
  191. of every word should be  highlighted by capitalizing the letter.  Example: 
  192. IndentifierName.
  193.  
  194. 3.    Limited Hungarian notation will be used.
  195. a    Atom
  196. b    BOOL (integer)
  197. by    BYTE (unsigned character)
  198. c    Character (ANSI ASCII 8-bit)
  199. dw    DWORD (unsigned long)
  200. fn    Function
  201. h    HANDLE (unsigned integer)
  202. hDC    HANDLE to a device context
  203. i    Integer
  204. id    Integral id value
  205. l    LONG (long)
  206. lp    Long (far) pointer
  207. lpsz    Long pointer to null-terminated string
  208. n    Short integer
  209. np    Near (short) pointer
  210. p    Pointer
  211. pfn    Function pointer
  212. pst    Pointer to a structure
  213. psz    Pointer to null-terminated string
  214. pv    Pointer to void
  215. s    String
  216. sz    NULL (/0) terminated string
  217. u    Unsigned
  218. v    Void
  219. w    WORD (unsigned integer)
  220. w    Character (Unicode 16-bit)
  221. x    Short (when used as the x coordinate)
  222. y    Short (when used as the y coordinate)
  223.  
  224. 4.    Filename constants must be exactly similar to the actual filename with 
  225. all-caps and an underscore to represent the delimiter between the prefix and 
  226. suffix.  
  227.         Example:    #define HELLO_H c:\subdir\hello.h
  228.  
  229.